Connecting to an ADO Client
You can connect to a data source using a Connection window, or using a provider string. See "Connecting with a Provider String" for information about connecting using an ADO provider string.
Testing ADO Connections
The ADO provider opens a Connection window when you perform either of the following actions:
See "ADO Connection Dialogs" for more information about ADO connection dialogs that may appear.
ADO Connection Dialogs
When your data consumer requests the ADO provider to prompt for missing connection parameters and an ADO data source has not been specified, the DataDirect SequeLink for ADO Provider Connection dialog box appears.
Select the data source that you want to use from the drop-down list. If you do not want to specify a data source name, select None from the drop-down list. In some cases, the data source name may be supplied automatically. Then, click OK.
The other connection dialogs that may appear involve prompting for information required to make a SequeLink data access connection.
A SequeLink data access connection involves the following stages:
- A network connection is established.
- An authentication mechanism is used to establish the identity of the SequeLink Client to the SequeLink Server.
- Based on information provided by the SequeLink Client application (for example, a database user name and password), a database connection is established.
Stage 1: Establishing a Network Connection
The first stage of the connection process involves establishing a network connection. The dialog that appears depends on whether the connection has been configured to connect directly to a SequeLink service or to retrieve connection information for the SequeLink service from a centralized LDAP directory.
Connecting Directly to a SequeLink® Service
If the connection has been configured to connect directly to a SequeLink service, the Connect to the SequeLink Server dialog box appears.
Provide the following information; then, click OK.
SequeLink Server Host: Type the TCP/IP host name of the SequeLink service.
SequeLink Server Port: Type the TCP/IP port on which the SequeLink service is listening. A default installation of SequeLink Server uses the port 19996.
Server Data Source: Type the name of a server data source to use for the connection or click the ... button to select an existing data source. This step is optional. If a server data source is not specified, the default server data source for that service will be used for the connection.
Retrieving Connection Information from an LDAP Directory
If the connection has been configured to connect to an LDAP server to retrieve connection information from an LDAP directory, the Connect to the SequeLink Server dialog box appears.
Provide the following information; then, click OK.
LDAP Server Host: Type the TCP/IP host name of the LDAP server.
LDAP Server Port: Type the TCP/IP port on which the LDAP server is listening.
Distinguished Name: Type the Distinguished Name (DN) of the LDAP entry.
For information about setting up an LDAP server for SequeLink, refer to the SequeLink Administrator's Guide.
Stage 2: SequeLink® Server Authentication
The second stage of the connection process involves authentication of the SequeLink Client to the SequeLink Server. The dialog boxes that appear depend on how authentication is configured for the SequeLink service.
- When ServiceAuthMethods=anonymous or ServiceAuthMethods=integrated_nt, no dialogs appear.
- When ServiceAuthMethods=OSLogon(HUID,HPWD) or ServiceAuthMethods=OSLogon(UID,PWD), the Logon to SequeLink Service dialog box appears.
- When ServiceAuthMethods=OSLogon(HUID,HPWD,NPWD) or ServiceAuthMethods=OSLogon(UID,PWD,NPWD) and the password is expired, the Password expired. Please specify new password dialog box appears.
Provide the following information; then, click OK.
Host User Name: Type the host user name.
NOTE: When connecting to a Windows server, you must prefix the host user name with a server name, if authenticating to a local server, or a domain name (for example, SALES\DJONES). If the server name or domain name is omitted, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the machine on which the SequeLink Server is running. If this validation fails, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the domain of the machine on which the SequeLink Server is running.
Host Password: Type the host password.
NOTE: If the password is not expired, the previous dialog appears. You are only prompted for the Host User Name and Host Password.
Provide the following information; then, click OK.
Host User Name: Type the host user name.
NOTE: When connecting to a Windows server, you must prefix the host user name with a server name, if authenticating to a local server, or a domain name (for example, SALES\DJONES). If the server name or domain name is omitted, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the machine on which the SequeLink Server is running. If this validation fails, the SequeLink Server will attempt to authenticate the user ID and password with the database account defined for the domain of the machine on which the SequeLink Server is running.
Host Password: Type the host password.
New Password: Type the new password to be used by the SequeLink password change mechanism.
Confirm Password: Type again the new password to confirm it.
For more information about configuring authentication, refer to the SequeLink Administrator's Guide.
Stage 3: Data Store Logon
The last stage of the connection process involves logging on the data store. The dialogs that appear depend on the data store logon method configured for the SequeLink service:
- When DataSourceLogonMethod=OSIntegrated, no dialogs appear.
- When DataSourceLogonMethod=DBMSLogon(UID,PWD) or DataSourceLogonMethod=DBMSLogon(DBUID,DBPWD), a data store-specific user name and password are required and the Logon to SequeLink Service dialog box appears.
Provide the following information; then, click OK.
Database User Name: Type the database logon ID.
Database Password: Type the database password.
Database: Type the name of the database to which you want to connect. This field is disabled when the data store does not recognize the concept of databases.
For more information about configuring data store logon methods, refer to the SequeLink Administrator's Guide.
Connecting with a Provider String
Once a data source is defined through the DataDirect Configuration Manager and the SequeLink for ADO Provider Setup Assistant, your application can connect directly to that data source. You can override the current settings for the data source when you connect using a provider string.
A provider string contains attribute=value pairs that control various aspects of the data provider's connection and interaction with the database. When an application names a specific data source to connect to, the application can also pass the data provider a provider string of attribute=value pairs. The data provider uses the values in the provider string instead of the default values defined for the data source in the system information.
Using provider strings allows application developers to configure connections for users programmatically and ensures that users have the optimum settings for working with the provider and database. Any values a user has set for a data source through the DataDirect Configuration Manager are overridden by corresponding values in the provider string for the current session only.
The provider string sets the DBPROP_INIT_PROVIDERSTRING initialization property and has the form:
You can specify the attribute=value pairs on the Options tab of the DataDirect SequeLink for ADO 6.0 Provider Setup window.
See "ADO Connection Attributes" for information about the ADO connection attributes.
ADO Connection Attributes
Table 3-2 provides a list of ADO connection attributes supported by the ADO provider. It lists a description for each attribute. The defaults listed in the table are initial defaults that apply when no value is specified in the provider string or in the data source definition in the system information. If you specified a value for the attribute when configuring the data source in the Setup window, that value is your default.
|
Attribute
|
Description
|
|---|---|
|
Alternate Servers
|
Specifies a list of alternate SequeLink servers that the data provider will try to connect to if the primary SequeLink server is unavailable. Specifying a value for this attribute enables connection failover for the data provider.
The value must be in the form of a string that defines connection information for each alternate SequeLink server. The Host and Port values are required for each alternate server entry. Connection options (property=value) are optional for each alternate server entry. The string has the format:
(Host=servername1:Port=port1[:property= value[:...]],Host=servername2:Port= port2[:property=value[:...]],...)
For example, the following Alternate Servers value defines two alternate SequeLink servers for connection failover:
Alternate Servers=(Host=AccountingSLServer:Port= 13999:APPName=SequeLink for ADO App,Host= AccountingAltServer:Port=13998:APPName=SequeLink for ADO App)
IMPORTANT: If you specify an LDAP server in the Host connection attribute, the alternate servers must be LDAP servers. For example, the following Alternate Servers value defines three alternate LDAP servers for connection failover:
See "Configuring Connection Failover" for a discussion of connection failover.
|
|
Application ID
|
Specifies the application ID that identifies the client application to the SequeLink service. This attribute is only required when the SequeLink service you are connecting to is configured to limit access to specific applications.
See "Specifying Application IDs" for more information about using application IDs to limit access to SequeLink services.
|
|
ApplicationName
|
Identifies the application that is establishing the connections (for example,
ApplicationName=Account01) and can be used to identify where problems that are associated with a particular application occur.
The initial default value is SequeLink for ADO Application.
|
|
Automatic Application ID
|
Specifies an application ID that is automatically generated by the ADO Client to identify the client application to the SequeLink service. This attribute is only required when the SequeLink service you are connecting to has been configured to limit access to specific applications.
See "Specifying Application IDs" for more information about using application IDs to limit access to SequeLink services.
|
|
Connection Retry Count
|
Specifies the number of times the data provider retries connection attempts to the primary SequeLink server, and if specified, alternate SequeLink servers after the first unsuccessful attempt. Valid values are 0 and any positive integer.
When set to 0 (the initial default), the data provider does not try to reconnect after the initial unsuccessful attempt.
For example, consider the following example:
Alternate Servers=(Host=server2:Port=19996,Host= server3:Port=19996,Host=server4:Port= 19999);Connection Retry Count=1;
If a connection is not successfully established on the data provider's first pass through the list of database servers, the data provider retries all the servers in the list one time.
See "Configuring Connection Failover" for a discussion of connection failover.
|
|
Connection Retry Delay
|
Specifies the seconds the data provider waits after the initial unsuccessful connection attempt before retrying a connection to the primary SequeLink server and, if specified, to the alternate SequeLink servers.
Valid values are integers from 0 to 65535.
The default value is 3 (seconds). When set to 0, there is no delay between retries.
NOTE: This option has no effect unless the Connection Retry Count connection option is set to an integer value greater than 0.
For example, in the following example:
Alternate Servers=(Host=server2:Port=19996,Host= server3:Port=19996,Host=server4:Port= 19996);Connection Retry Count=2;Connection Retry Delay=3
If a connection is not successfully established on the data provider's first pass through the list of SequeLink servers, the data provider retries the list of servers twice. It waits 3 seconds between the first and second connection retry attempts.
See "Configuring Connection Failover" for a discussion of connection failover.
|
|
Database
|
Specifies the name of the database to which you want to connect.
|
|
Database User Name
|
Specifies the data store user name, which may be required depending on the server configuration.
|
|
Database Password
|
Specifies the data store password, which may be required depending on the server configuration.
|
|
Data Source
|
Specifies a string that identifies an ADO/OLE DB data source configuration. Examples include
Accounting or SequeLink to Oracle Data.
|
|
Default Length for Long Data
|
Turns on a workaround that allows you to specify the amount of data (in KB) that is buffered for SQL_LONGVARCHAR and SQL_LONGVARBINARY columns with a static cursor.
The initial default value is 4.
|
|
Distinguished Name
|
Specifies the distinguished name identifying the LDAP entry from which connection information is retrieved. This attribute is required when UseLDAP=1.
|
|
Encrypted
|
Encrypted={0 | 1}. Enables the use of SSL encryption if the remote SequeLink service the client is connecting to is configured for SSL.
When set to 0 (the default), the data provider does not use SSL encryption for data exchanged with the SequeLink Server.
When set to 1, the data provider uses SSL encryption. This attribute must be set to 1 when connecting to a SequeLink service enabled for SSL.
For more information about encrypting data, refer to the SequeLink Administrator's Guide.
NOTE: Encrypted (SSL) is not supported for LDAP Servers. The Use LDAP and the Encrypted (SSL) attributes are mutually exclusive.
|
|
Host
|
Specifies the TCP/IP address of the SequeLink Server, specified in dotted format or as a host name.
LDAP: If LDAP is enabled, this identifies the TCP/IP address of the LDAP server. This can also be a list of LDAP servers separated by a blank space (for example, "
ld1.foo.com ld2.foo.com ld3.foo.com"). If the first LDAP server in the list does not respond, the data provider will try to connect to the next LDAP server in the list.
NOTE: If you want to use connection failover features such as connection retry and load balancing, specify the alternate LDAP servers in the Alternate Servers connection attribute. See "Configuring Connection Failover" for more information about connection failover.
|
|
Host Password
|
Specifies the host password, which may be required depending on the server configuration.
|
|
Host User Name
|
Specifies the host user name, which may be required depending on the server configuration.
|
|
Load Balancing
|
Load Balancing={0 | 1}. Determines whether the data provider uses client load balancing in its attempts to connect to a list of SequeLink servers (primary and alternate). The list of alternate servers is specified by the Alternate Servers attribute.
When set to 1, client load balancing is used and the data provider attempts to connect to the list of SequeLink servers (primary and alternate servers) in random order.
If set to 0 (the default), client load balancing is not used and the driver connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified).
In the following example:
Host=server1;Port=19996;User ID=test;Password= secret;Alternate Servers=(Host=server2:Port= 19996,Host=server3:Port=19996, Host=server4:Port= 19996);Load Balancing=1;
The data provider randomly selects a SequeLink server from the list of primary and alternate servers and attempts to connect. If that connection attempt fails, the data provider again randomly selects a SequeLink server from this list until all of the servers have been tried or a connection is successfully established.
See "Configuring Connection Failover" for more information about connection failover.
|
|
New Password
|
Specifies the new host password to be used. If specified and applicable to the connection, the SequeLink password change mechanism is invoked. When the password has been changed successfully, the following warning is generated:
[DataDirect][SequeLink ADO Provider]
If unspecified and the SequeLink Server detects that the host password has expired, you will be prompted for a new host password.
For more information about the SequeLink password change mechanism, refer to the SequeLink Administrator's Guide.
|
|
Password
|
Specifies the host or data store password, which may be required depending on the server configuration.
|
|
Port
|
Specifies the TCP/IP port on which the SequeLink Server is listening.
LDAP: If LDAP is enabled, this identifies the TCP/IP port on which the LDAP server is listening. If you do not specify a port, the default port for LDAP (389) will be used.
|
|
Server Data Source
|
Optionally, identifies the server data source to be used for the connection. If not specified, the configuration of the default server data source will be used for the connection.
|
|
Use LDAP
|
Use LDAP={0 | 1}. Determines whether the parameters to establish a connection to the SequeLink Server should be retrieved from LDAP.
When set to 0, the SequeLink Client will connect directly to the specified SequeLink Server.
When set to 1, the SequeLink Client will retrieve the TCP/IP host, TCP/IP port, and SequeLink data source (optional) from an LDAP entry identified by a Distinguished Name (DN). Once the connection information is retrieved, the SequeLink Client will connect directly to the specified SequeLink Server. The DistinguishedName (DN) attribute is required.
The initial default value is 0.
NOTE: Encryption (SSL) is not supported for LDAP Servers. The Use LDAP and the Encrypted (SSL) attributes are mutually exclusive.
|
|
User ID
|
Specifies the host or data store user name, which may be required depending on the server configuration.
|